<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Customizing roles and authorization | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'custom-roles-authorization.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/custom-roles-authorization.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/custom-roles-authorization.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/custom-roles-authorization.html" rel="nofollow" target="_blank">../en/custom-roles-authorization.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="authorization.html">User authorization</a></span>
»
<span class="breadcrumb-node">Customizing roles and authorization</span>
</div>
<div class="navheader">
<span class="prev">
<a href="configuring-authorization-delegation.html">« Configuring authorization delegation</a>
</span>
<span class="next">
<a href="enable-audit-logging.html">Enabling audit logging »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="custom-roles-authorization"></a>Customizing roles and authorization<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/custom-authorization.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h2>
</div></div></div>
<p>If you need to retrieve user roles from a system not supported out-of-the-box
or if the authorization system that is provided by the Elasticsearch security features
does not meet your needs, a SPI loaded security extension can be implemented to
customize role retrieval and/or the authorization system. The SPI loaded
security extension is part of an ordinary elasticsearch plugin.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="implementing-custom-roles-provider"></a>Implementing a custom roles provider<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/custom-authorization.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To create a custom roles provider:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Implement the interface <code class="literal">BiConsumer&lt;Set&lt;String&gt;, ActionListener&lt;Set&lt;RoleDescriptor&gt;&gt;&gt;</code>.
That is to say, the implementation consists of one method that takes a set of strings,
which are the role names to resolve, and an ActionListener, on which the set of resolved
role descriptors are passed on as the response.
</li>
<li class="listitem">
The custom roles provider implementation must take special care to not block on any I/O
operations.  It is the responsibility of the implementation to ensure asynchronous behavior
and non-blocking calls, which is made easier by the fact that the <code class="literal">ActionListener</code> is
provided on which to send the response when the roles have been resolved and the response
is ready.
</li>
</ol>
</div>
<p>To package your custom roles provider as a plugin:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Implement an extension class for your roles provider that implements
<code class="literal">org.elasticsearch.xpack.core.security.SecurityExtension</code>. There you need to
override one or more of the following methods:</p>
<div class="pre_wrapper lang-java">
<pre class="programlisting prettyprint lang-java">@Override
public List&lt;BiConsumer&lt;Set&lt;String&gt;, ActionListener&lt;Set&lt;RoleDescriptor&gt;&gt;&gt;&gt;
getRolesProviders(Settings settings, ResourceWatcherService resourceWatcherService) {
    ...
}</pre>
</div>
<p>The <code class="literal">getRolesProviders</code> method is used to provide a list of custom roles providers that
will be used to resolve role names, if the role names could not be resolved by the reserved
roles or native roles stores.   The list should be returned in the order that the custom role
providers should be invoked to resolve roles.  For example, if <code class="literal">getRolesProviders</code> returns two
instances of roles providers, and both of them are able to resolve role <code class="literal">A</code>, then the resolved
role descriptor that will be used for role <code class="literal">A</code> will be the one resolved by the first roles
provider in the list.</p>
</li>
</ol>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="implementing-authorization-engine"></a>Implementing an authorization engine<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/custom-authorization.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To create an authorization engine, you need to:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Implement the <code class="literal">org.elasticsearch.xpack.core.security.authz.AuthorizationEngine</code>
interface in a class with the desired authorization behavior.
</li>
<li class="listitem">
Implement the <code class="literal">org.elasticsearch.xpack.core.security.authz.Authorization.AuthorizationInfo</code>
interface in a class that contains the necessary information to authorize the request.
</li>
</ol>
</div>
<p>To package your authorization engine as a plugin:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Implement an extension class for your authorization engine that extends
<code class="literal">org.elasticsearch.xpack.core.security.SecurityExtension</code>. There you need to
override the following method:</p>
<div class="pre_wrapper lang-java">
<pre class="programlisting prettyprint lang-java">@Override
public AuthorizationEngine getAuthorizationEngine(Settings settings) {
    ...
}</pre>
</div>
<p>The <code class="literal">getAuthorizationEngine</code> method is used to provide the authorization engine
implementation.</p>
</li>
</ol>
</div>
<p>Sample code that illustrates the structure and implementation of a custom
authorization engine is provided in the
<a href="https://github.com/elastic/elasticsearch/tree/master/plugins/examples/security-authorization-engine" class="ulink" target="_top">elasticsearch</a>
repository on GitHub. You can use this code as a starting point for creating your
own authorization engine.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="packing-extension-plugin"></a>Implement an elasticsearch plugin<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/custom-authorization.asciidoc">edit</a>
</h3>
</div></div></div>
<p>In order to register the security extension for your custom roles provider or
authorization engine, you need to also implement an elasticsearch plugin that
contains the extension:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Implement a plugin class that extends <code class="literal">org.elasticsearch.plugins.Plugin</code>
</li>
<li class="listitem">
Create a build configuration file for the plugin; Gradle is our recommendation.
</li>
<li class="listitem">
Create a <code class="literal">plugin-descriptor.properties</code> file as described in
<a href="https://www.elastic.co/guide/en/elasticsearch/plugins/7.7/plugin-authors.html" class="ulink" target="_top">Help for plugin authors</a>.
</li>
<li class="listitem">
Create a <code class="literal">META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension</code> descriptor file for the
extension that contains the fully qualified class name of your <code class="literal">org.elasticsearch.xpack.core.security.SecurityExtension</code> implementation
</li>
<li class="listitem">
Bundle all in a single zip file.
</li>
</ol>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="using-security-extension"></a>Using the security extension<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/custom-authorization.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To use a security extension:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Install the plugin with the extension on each node in the cluster. You run
<code class="literal">bin/elasticsearch-plugin</code> with the <code class="literal">install</code> sub-command and specify the URL
pointing to the zip file that contains the extension. For example:</p>
<div class="pre_wrapper lang-shell">
<pre class="programlisting prettyprint lang-shell">bin/elasticsearch-plugin install file:///&lt;path&gt;/my-extension-plugin-1.0.zip</pre>
</div>
</li>
<li class="listitem">
<p>Add any configuration parameters for implementations in the extension to the
<code class="literal">elasticsearch.yml</code> file.  The settings are not namespaced and you have access to any
settings when constructing the extensions, although it is recommended to have a
namespacing convention for extensions to keep your <code class="literal">elasticsearch.yml</code>
configuration easy to understand.</p>
<p>For example, if you have a custom roles provider that
resolves roles from reading a blob in an S3 bucket on AWS, then you would specify settings
in <code class="literal">elasticsearch.yml</code> such as:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">custom_roles_provider.s3_roles_provider.bucket: roles
custom_roles_provider.s3_roles_provider.region: us-east-1
custom_roles_provider.s3_roles_provider.secret_key: xxx
custom_roles_provider.s3_roles_provider.access_key: xxx</pre>
</div>
<p>These settings are passed as arguments to the methods in the <code class="literal">SecurityExtension</code> interface.</p>
</li>
<li class="listitem">
Restart Elasticsearch.
</li>
</ol>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="configuring-authorization-delegation.html">« Configuring authorization delegation</a>
</span>
<span class="next">
<a href="enable-audit-logging.html">Enabling audit logging »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>